{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n",
    "SPDX-License-Identifier: Apache-2.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# What are Neptune Notebooks?\n",
    "\n",
    "The workbench is an interactive environment that hosts [Jupyter notebooks](https://jupyter-notebook.readthedocs.io/en/stable/) along with a set of tools that make it easy to get started with Neptune. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What is a Jupyter notebook?\n",
    "\n",
    "Jupyter is a web-based application that lets you author and interact with 'notebook' documents.  The [Jupyter](https://jupyter.org/) open-source project that develops it provides [documentation](https://jupyter-notebook.readthedocs.io/en/stable/) of its own.\n",
    "\n",
    "A notebook document consists of a series of 'cells'. A cell can contain one of:\n",
    "\n",
    "- Explanatory text authored in Markdown, or\n",
    "- Code that you can run (the programming language depends on the kernel that your server is using), or\n",
    "- The output that is produced when you run the code.\n",
    "\n",
    "The user interface of a notebook is fairly self-explanatory. You can create a new notebook from the `File` menu. Once you have a notebook open, you can edit a cell by double-clicking on its interior. If you are editing a Markdown cell, you can render its HTML by \"running\" it. You can run a selected cell using the `Run` button on the toolbar (if the toolbar is hidden, use the `View` menu to toggle it on). The `Edit` and `Cell` menus provide a large number of operations, and `Keyboard Shortcuts` on the `Help` menu displays a long list of commands with corresponding key shortcuts.\n",
    "\n",
    "Markdown text cells have a height limit, which forces you to break explanations into small, manageable blocks.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Features\n",
    "\n",
    "You can use notebooks in the workbench to load and interact with data and your graph.  For example, you can heck the database status using the `status` endpoint, and try out to make queries against your database using openCypher, Gremlin, or SPARQL.\n",
    "\n",
    "By default, the workbench uses the IPython 3 kernel. It also provides a number of useful extensions:\n",
    "\n",
    "#### Notebook cell 'magic' extensions in the IPython 3 kernel\n",
    "`%%sparql` - Executes a SPARQL query against your configured database endpoint. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-sparql)\n",
    "\n",
    "`%%gremlin` - Executes a Gremlin query against your database using web sockets. The results are similar to those a Gremlin console would return. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-gremlin)\n",
    "\n",
    "`%%opencypher` or `%%oc` Executes an openCypher query against your database. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-opencypher)\n",
    "\n",
    "`%%graph_notebook_config` - Sets the executing notebook's database configuration to the JSON payload provided in the cell body.\n",
    "\n",
    "`%%graph_notebook_vis_options` - Sets the executing notebook's [vis.js options](https://visjs.github.io/vis-network/docs/network/physics.html) to the JSON payload provided in the cell body.\n",
    "\n",
    "`%%neptune_ml` - Set of commands to integrate with NeptuneML functionality, as described [here](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-line-magics-neptune_ml). [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/machine-learning.html)\n",
    "\n",
    "**TIP** :point_right: `%%sparql`, `%%gremlin`, and `%%oc` share a [suite of common arguments](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebook-magics-query-args) that be used to customize the appearance of rendered graphs. Example usage of these arguments can also be found in the sample notebooks under [02-Visualization](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/02-Visualization).\n",
    "\n",
    "**TIP** :point_right: There is syntax highlighting for language query magic cells to help you structure your queries more easily.\n",
    "\n",
    "#### Notebook line 'magic' extensions in the IPython 3 kernel\n",
    "`%gremlin_status` - Obtain the status of Gremlin queries. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/gremlin-api-status.html)\n",
    "\n",
    "`%sparql_status` - Obtain the status of SPARQL queries. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/sparql-api-status.html)\n",
    "\n",
    "`%opencypher_status` or `%oc_status` - Obtain the status of openCypher queries. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-opencypher-status.html)\n",
    "\n",
    "`%load` - Generate a form to submit a bulk loader job. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load.html)\n",
    "\n",
    "`%load_ids` - Get ids of bulk load jobs. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/load-api-reference-status-examples.html)\n",
    "\n",
    "`%load_status` - Get the status of a provided `load_id`. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/load-api-reference-status-examples.html)\n",
    "\n",
    "`%cancel_load` - Cancels a bulk load job. You can either provide a single `load_id`, or specify `--all-in-queue` to cancel all queued (and not actively running) jobs. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/load-api-reference-cancel.html)\n",
    "\n",
    "`%neptune_ml` - Set of commands to integrate with NeptuneML functionality, as described [here](https://docs.aws.amazon.com/neptune/latest/userguide/notebooks-magics.html#notebooks-cell-magics-neptune_ml). You can find a set of tutorial notebooks [here](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/04-Machine-Learning).\n",
    "[Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/machine-learning.html)\n",
    "\n",
    "`%status` - Check the Health Status of the configured host endpoint. [Documentation](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-status.html)\n",
    "\n",
    "`%seed` - Provides a form to add data to your graph without the use of a bulk loader. Supports both RDF and Property Graph data models.\n",
    "\n",
    "`%stream_viewer` - Interactively explore the Neptune CDC stream (if enabled)\n",
    "\n",
    "`%graph_notebook_config` - Returns a JSON payload that contains connection information for your host.\n",
    "\n",
    "`%graph_notebook_host` - Set the host endpoint to send queries to.\n",
    "\n",
    "`%graph_notebook_version` - Print the version of the `graph-notebook` package\n",
    "\n",
    "`%graph_notebook_vis_options` - Print the Vis.js options being used for rendered graphs\n",
    "\n",
    "\n",
    "### Feature Support\n",
    "\n",
    "All the extensions listed are supported by Neptune Database, however only a subset are supported by Neptune Analytics.  Those supported by Neptune Analytics are listed below:\n",
    "\n",
    "* Cell Magics\n",
    "    * `%%opencypher` or `%%oc`\n",
    "    * `%%graph_notebook_config`\n",
    "    * `%%graph_notebook_vis_options` \n",
    "* Line Magics\n",
    "    * `%opencypher_status` or `%oc_status`\n",
    "    * `%status`\n",
    "    * `%graph_notebook_config`\n",
    "    * `%graph_notebook_host`\n",
    "    * `%graph_notebook_version`\n",
    "    * `%graph_notebook_vis_options`\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Let's check our configuration and Neptune cluster status\n",
    "\n",
    "Before we start running any queries let's first of all make sure we are connected to Neptune and that the cluster is ready. Note that `%graph_notebook_config` will return the current configuration of your notebook. \n",
    "\n",
    "If, for example, you wanted to connect to a different Amazon Neptune endpoint you could create a cell with `%%graph_notebook_config` at the top, paste the results from running `%graph_notebook_config` into it, make the required edits and run the cell. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%graph_notebook_version"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%graph_notebook_config"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%status"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using a different endpoint\n",
    "You can change the endpoint that this notebook is connected to at any time using the `%graph_notebook_host` or `%%graph_notebook_config` commands. Edit and run the cell below whenever you need to change the endpoint you are connected to."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "%graph_notebook_host your-hostname-here"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next Steps\n",
    "\n",
    "Now that we have learned some basics about how the notebooks work, below are some recommended notebooks to continue your journey with Neptune.\n",
    "\n",
    "* If you are looking to build building mission-critical systems that leverage Neptune Database then you should continue on to the [01-Neptune-Database](./01-Neptune-Database/Overview.ipynb) folder.\n",
    "\n",
    "* If you are looking to use graph analytics and algorithms, low latency analytic queries, or Vector Similarity Search (VSS) with graph traversals. then you should continue on with the [02-Neptune-Analytics](./02-Neptune-Analytics/Overview.ipynb) folder. \n",
    "\n",
    "* If you are looking to build and train machine learning models on large graphs the please continue to the [03-Neptune-ML](./03-Neptune-ML/Overview.ipynb) folder. "
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
